home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / lib / X11 / xkb / README.enhancing < prev    next >
Text File  |  2005-01-13  |  23KB  |  510 lines

  1.                   How to further enhance XKB configuration
  2.  
  3.                          Kamil Toman, Ivan U. Pascal
  4.  
  5.                               25 November 2002
  6.  
  7.                                   Abstract
  8.  
  9.      This guide is aimed to relieve one's labour to create a new (inter-
  10.      nationalized) keyboard layout. Unlike other documents this guide
  11.      accents the keymap developer's point of view.
  12.  
  13. 1.  Overview
  14.  
  15. The developer of a new layout should read the xkb protocol specification (The
  16. X Keyboard Extension: Protocol Specification <URL:http://www.x-
  17. docs.org/XKB/XKBproto.pdf>) at least to clarify for himself some xkb-specific
  18. terms used in this document and elsewhere in xkb configuration. Also it shows
  19. wise to understand how the X server and a client digest their keyboard inputs
  20. (with and without xkb).
  21.  
  22. A useful source is also Ivan  Pascal's text about xkb configuration
  23. <URL:http://www.tsu.ru/~pascal/en/xkb> often referenced throughout this docu-
  24. ment.
  25.  
  26. Note that this document covers only enhancements which are to be made to
  27. XFree86 version 4.3 and X11R6.7.0 and above.
  28.  
  29. 2.  The Basics
  30.  
  31. At the startup (or at later at user's command) X server starts its xkb key-
  32. board module extension and reads data from a compiled configuration file.
  33.  
  34. This compiled configuration file is prepared by the program xkbcomp which
  35. behaves altogether as an ordinary compiler (see man xkbcomp).  Its input are
  36. human readable xkb configuration files which are verified and then composed
  37. into a useful xkb configuration. Users don't need to mess with xkbcomp them-
  38. selves, for them it is invisible. Usually, it is started upon X server
  39. startup.
  40.  
  41. As you probably already know, the xkb configuration consists of five main
  42. modules:
  43.  
  44.       Keycodes
  45.             Tables that defines translation from keyboard scan codes into
  46.             reasonable symbolic names, maximum, minimum legal keycodes, sym-
  47.             bolic aliases and description of physically present LED-indica-
  48.             tors. The primary sence of this component is to allow definitions
  49.             of maps of symbols (see below) to be independent of physical key-
  50.             board scancodes. There are two main naming conventions for sym-
  51.             bolic names (always four bytes long):
  52.  
  53.                o  names which express some traditional meaning like <SPCE>
  54.                  (stands for space bar) or
  55.  
  56.                o  names which express some relative positioning on a key-
  57.                  board, for example <AE01> (an exclamation mark on US key-
  58.                  boards), on the right there are keys <AE02>, <AE03> etc.
  59.  
  60.       Types
  61.             Types describe how the produced key is changed by active modi-
  62.             fiers (like Shift, Control, Alt, ...). There are several prede-
  63.             fined types which cover most of used combinations.
  64.  
  65.       Compat
  66.             Compatibility component defines internal behaviour of modifiers.
  67.             Using compat component you can assign various actions (elabo-
  68.             rately described in xkb specification) to key events. This is
  69.             also the place where LED-indicators behaviour is defined.
  70.  
  71.       Symbols
  72.             For i18n purposes, this is the most important table. It defines
  73.             what values (=symbols) are assigned to what keycodes (represented
  74.             by their symbolic name, see above). There may be defined more
  75.             than one value for each key and then it depends on a key type and
  76.             on modifiers state (respective compat component) which value will
  77.             be the resulting one.
  78.  
  79.       Geometry
  80.             Geometry files aren't used by xkb itself but they may be used by
  81.             some external programs to depict a keyboard image.
  82.  
  83. All these components have the files located in xkb configuration tree in sub-
  84. directories with the same names (usually in /usr/lib/X11/xkb).
  85.  
  86. 3.  Enhancing XKB Configuration
  87.  
  88. Most of xkb enhancements concerns a need to define new output symbols for the
  89. some input key events. In other words, a need to define a new symbol map (for
  90. a new language, standard or just to feel more comfortable when typing text).
  91.  
  92. What do you need to do? Generally, you have to define following things:
  93.  
  94.    o  the map of symbols itself
  95.  
  96.    o  the rules to allow users to select the new mapping
  97.  
  98.    o  the description of the new layout
  99.  
  100. First of all, it is good to go through existing layouts and to examine them
  101. if there is something you could easily adjust to fit your needs.  Even if
  102. there is nothing similar you may get some ideas about basic concepts and used
  103. tricks.
  104.  
  105. 3.1  Levels And Groups
  106.  
  107. Since XFree86 4.3.0 and X11R6.7.0 you can use multi-layout concept of xkb
  108. configuration.  Though it is still in boundaries of xkb protocol and general
  109. ideas, the keymap designer must obey new rules when creating new maps. In
  110. exchange we get a more powerful and cleaner configuration system.
  111.  
  112. Remember that it is the application which must decide which symbol matches
  113. which keycode according to effective modifier state. The X server itself
  114. sends only an input event message to. Of course, usually the general inter-
  115. pretation is processed by Xlib, Xaw, Motif, Qt, Gtk and similar libraries.
  116. The X server only supplies its mapping table (usually upon an application
  117. startup).
  118.  
  119. You can think of the X server's symbol table as of a irregular table where
  120. each keycode has its row and where each combination of modifiers determines
  121. exactly one column. The resulting cell then gives the proper symbolic value.
  122. Not all keycodes need to bind different values for different combination of
  123. modifiers.  <ENTER> key, for instance, usually doesn't depend on any modi-
  124. fiers so it its row has only one column defined.
  125.  
  126. Note that in XKB there is no prior assumption that certain modifiers are
  127. bound to certain columns. By editing proper files (see refnam (section 4.2,
  128. page 1)) this mapping can be changed as well.
  129.  
  130. Unlike the original X protocol the XKB approach is far more flexible. It is
  131. comfortable to add one additional XKB term - group. You can think of a group
  132. as of a vector of columns per each keycode (naturally the dimension of this
  133. vector may differ for different keycodes). What is it good for? The group is
  134. not very useful unless you intend to use more than one logically different
  135. set of symbols (like more than one alphabet) defined in a single mapping
  136. table. But then, the group has a natural meaning - each symbol set has its
  137. own group and changing it means selecting a different one.  XKB approach
  138. allows up to four different groups. The columns inside each group are called
  139. (shift) levels. The X server knows the current group and reports it together
  140. with modifier set and with a keycode in key events.
  141.  
  142. To sum it up:
  143.  
  144.    o  for each keycode XKB keyboard map contains up to four one-dimensional
  145.      tables - groups (logically different symbol sets)
  146.  
  147.    o  for each group of a keycode XKB keyboard map contains some columns -
  148.      shift levels (values reached by combinations of Shift, Ctrl, Alt, ...
  149.      modifiers)
  150.  
  151.    o  different keycodes can have different number of groups
  152.  
  153.    o  different groups of one keycode can have different number of shift lev-
  154.      els
  155.  
  156.    o  the current group number is tracked by X server
  157.  
  158. It is clear that if you sanely define levels, groups and sanely bind modi-
  159. fiers and associated actions you can have simultaneously loaded up to four
  160. different symbol sets where each of them would reside in its own group.
  161.  
  162. The multi-layout concept provides a facility to manipulate xkb groups and
  163. symbol definitions in a way that allows almost arbitrary composition of pre-
  164. defined symbol tables. To keep it fully functional you have to:
  165.  
  166.    o  define all symbols only in the first group
  167.  
  168.    o  (re)define any modifiers with extra care to avoid strange (anisometric)
  169.      behaviour
  170.  
  171. 4.  Defining New Layouts
  172.  
  173. See Some Words  About XKB internals <URL:http://www.tsu.ru/~pas-
  174. cal/en/xkb/internals.html> for explanation of used xkb terms and problems
  175. addressed by XKB extension.
  176.  
  177. See Common  notes about XKB configuration files language
  178. <URL:http://www.tsu.ru/~pascal/en/xkb/gram-common.html> for more precise
  179. explanation of syntax of xkb configuration files.
  180.  
  181. 4.1  Predefined XKB Symbol Sets
  182.  
  183. If you are about to define some European symbol map extension, you might want
  184. to use on of four predefined latin alphabet layouts.
  185.  
  186. Okay, let's assume you want extend an existing keymap and you want to over-
  187. ride a few keys. Let's take a simple U.K. keyboard as an example (defined in
  188. pc/gb):
  189.  
  190.      partial default alphanumeric_keys
  191.      xkb_symbols "basic" {
  192.        include "pc/latin"
  193.  
  194.        name[Group1]="Great Britain";
  195.  
  196.        key <AE02>  { [         2,   quotedbl,  twosuperior,    oneeighth ] };
  197.        key <AE03>  { [         3,   sterling, threesuperior,    sterling ] };
  198.        key <AC11>  { [apostrophe,         at, dead_circumflex, dead_caron] };
  199.        key <TLDE>  { [     grave,    notsign,          bar,          bar ] };
  200.        key <BKSL>  { [numbersign, asciitilde,   dead_grave,   dead_breve ] };
  201.        key <RALT>  { type[Group1]="TWO_LEVEL",
  202.                      [ ISO_Level3_Shift, Multi_key ]   };
  203.  
  204.        modifier_map Mod5   { <RALT> };
  205.      };
  206.  
  207. It defines a new layout in basic variant as an extension of common latin
  208. alphabet layout. The layout (symbol set) name is set to "Great Britain".
  209. Then there are redefinitions of a few keycodes and a modifiers binding. As
  210. you can see the number of shift levels is the same for <AE02>, <AE03>,
  211. <AC11>, <TLDE> and <BKSL> keys but it differs from number of shift levels of
  212. <RALT>.
  213.  
  214. Note that the <RALT> key itself is a binding key for Mod5 and that it serves
  215. like a shift modifier for LevelThree, together with Shift as a multi-key. It
  216. is a good habit to respect this rule in a new similar layout.
  217.  
  218. Okay, you could now define more variants of your new layout besides basic
  219. simply by including (augmenting/overriding/...) the basic definition and
  220. altering what may be needed.
  221.  
  222. 4.2  Key Types
  223.  
  224. The differences in the number of columns (shift levels) are caused by a dif-
  225. ferent types of keys (see the types definition in section basics).  Most key-
  226. codes have implicitly set the keytype in the included 'pc/latin' file to
  227. 'FOUR_LEVEL_ALPHABETIC'. The only exception is <RALT> keycode which is
  228. explicitly set 'TWO_LEVEL' keytype.
  229.  
  230. All those names refer to pre-defined shift level schemes. Usually you can
  231. choose a suitable shift level scheme from default types scheme list in proper
  232. xkb component's subdirectory.
  233.  
  234. The most used schemes are:
  235.  
  236.       ONE_LEVEL
  237.             The key does not depend on any modifiers. The symbol from first
  238.             level is always chosen.
  239.  
  240.       TWO_LEVEL
  241.             The key uses a modifier Shift and may have two possible values.
  242.             The second level may be chosen by Shift modifier. If Lock modi-
  243.             fier (usually Caps-lock) applies the symbol is further processed
  244.             using system-specific capitalization rules. If both Shift+Lock
  245.             modifier apply the symbol from the second level is taken and cap-
  246.             italization rules are applied (and usually have no effect).
  247.  
  248.       ALPHABETIC
  249.             The key uses modifiers Shift and Lock. It may have two possible
  250.             values. The second level may be chosen by Shift modifier. When
  251.             Lock modifier applies, the symbol from the first level is taken
  252.             and further processed using system-specific capitalization rules.
  253.             If both Shift+Lock modifier apply the symbol from the first level
  254.             is taken and no capitalization rules applied. This is often
  255.             called shift-cancels-caps behaviour.
  256.  
  257.       THREE_LEVEL
  258.             Is the same as TWO_LEVEL but it considers an extra modifier -
  259.             LevelThree which can be used to gain the symbol value from the
  260.             third level. If both Shift+LevelThree modifiers apply the value
  261.             from the third level is also taken. As in TWO_LEVEL, the Lock
  262.             modifier doesn't influence the resulting level. Only Shift and
  263.             LevelThree are taken into that consideration. If the Lock modi-
  264.             fier is active capitalization rules are applied on the resulting
  265.             symbol.
  266.  
  267.       FOUR_LEVEL
  268.             Is the same as THREE_LEVEL but unlike LEVEL_THREE if both
  269.             Shift+LevelThree modifiers apply the symbol is taken from the
  270.             fourth level.
  271.  
  272.       FOUR_LEVEL_ALPHABETIC
  273.             Is similar to FOUR_LEVEL but also defines shift-cancels-caps
  274.             behaviour as in ALPHABETIC. If Lock+LevelThree apply the symbol
  275.             from the third level is taken and the capitalization rules are
  276.             applied.  If Lock+Shift+LevelThree apply the symbol from the
  277.             third level is taken and no capitalization rules are applied.
  278.  
  279.       KEYPAD
  280.             As the name suggest this scheme is primarily used for numeric
  281.             keypads.  The scheme considers two modifiers - Shift and NumLock.
  282.             If none of modifiers applies the symbol from the first level is
  283.             taken. If either Shift or NumLock modifiers apply the symbol from
  284.             the second level is taken.  If both Shift+NumLock modifiers apply
  285.             the symbol from the first level is taken. Again, shift-cancels-
  286.             caps variant.
  287.  
  288.       FOUR_LEVEL_KEYPAD
  289.             Is similar to KEYPAD scheme but considers also LevelThree modi-
  290.             fier.  If LevelThree modifier applies the symbol from the third
  291.             level is taken.  If Shift+LevelThree or NumLock+LevelThree apply
  292.             the symbol from the fourth level is taken. If all Shift+Num-
  293.             Lock+LevelThree modifiers apply the symbol from the third level
  294.             is taken. This also, shift-cancels-caps variant.
  295.  
  296. Besides that, there are several schemes for special purposes:
  297.  
  298.       PC_BREAK
  299.             It is similar to TWO_LEVEL scheme but it considers the Control
  300.             modifier rather than Shift. That means, the symbol from the sec-
  301.             ond level is chosen by Control rather than by Shift.
  302.  
  303.       PC_SYSRQ
  304.             It is similar to TWO_LEVEL scheme but it considers the Alt modi-
  305.             fier rather than Shift. That means, the symbol from the second
  306.             level is chosen by Alt rather than by Shift.
  307.  
  308.       CTRL+ALT
  309.             The key uses modifiers Alt and Control. It may have two possible
  310.             values. If only one modifier (Alt or Control) applies the symbol
  311.             from the first level is chosen. Only if both Alt+Control modi-
  312.             fiers apply the symbol from the second level is chosen.
  313.  
  314.       SHIFT+ALT
  315.             The key uses modifiers Shift and Alt. It may have two possible
  316.             values.  If only one modifier (Alt or Shift) applies the symbol
  317.             from the first level is chosen. Only if both Alt+Shift modifiers
  318.             apply the symbol from the second level is chosen.
  319.  
  320. If needed, special caps schemes may be used. They redefine the standard
  321. behaviour of all *ALPHABETIC types. The layouts (maps of symbols) with keys
  322. defined in respective types then automatically change their behaviour accord-
  323. ingly. Possible redefinitions are:
  324.  
  325.    o internal
  326.  
  327.    o internal_nocancel
  328.  
  329.    o shift
  330.  
  331.    o shift_nocancel
  332.  
  333. None of these schemes should be used directly. They are defined merely for
  334. 'caps:' xkb options (used to globally change the layouts behaviour).
  335.  
  336. Don't alter any of existing key types. If you need a different behaviour cre-
  337. ate a new one.
  338.  
  339. 4.2.1  More On Definitions Of Types
  340.  
  341. When the XKB software deals with a separate type description it gets a com-
  342. plete list of modifiers that should be taken into account from the 'modi-
  343. fiers=<list of modifiers>' list and expects that a set of 'map[<combination
  344. of modifiers>]=<list of modifiers>' instructions that contain the mapping for
  345. each combination of modifiers mentioned in that list. Modifiers that are not
  346. explicitly listed are NOT taken into account when the resulting shift level
  347. is computed.  If some combination is omitted the program (subroutine) should
  348. choose the first level for this combination (a quite reasonable behavior).
  349.  
  350. Lets consider an example with two modifiers ModOne and ModTwo:
  351.  
  352.      type "..." {
  353.          modifiers = ModOne+ModTwo;
  354.          map[None] = Level1;
  355.          map[ModOne] = Level2;
  356.      };
  357.  
  358. In this case the map statements for ModTwo only and ModOne+ModTwo are omit-
  359. ted.  It means that if the ModTwo is active the subroutine can't found
  360. explicit mapping for such combination an will use the default level i.e.
  361. Level1.
  362.  
  363. But in the case the type described as:
  364.  
  365.      type "..." {
  366.          modifiers = ModOne;
  367.          map[None] = Level1;
  368.          map[ModOne] = Level2;
  369.      };
  370.  
  371. the ModTwo will not be taken into account and the resulting level depends on
  372. the ModOne state only. That means, ModTwo alone produces the Level1 but the
  373. combination ModOne+ModTwo produces the Level2 as well as ModOne alone.
  374.  
  375. What does it mean if the second modifier is the Lock? It means that in the
  376. first case (the Lock itself is included in the list of modifiers but combina-
  377. tions with this modifier aren't mentioned in the map statements) the internal
  378. capitalization rules will be applied to the symbol from the first level. But
  379. in the second case the capitalization will be applied to the symbol chosen
  380. accordingly to he first modifier - and this can be the symbol from the first
  381. as well as from the second level.
  382.  
  383. Usually, all modifiers introduced in 'modifiers=<list of modifiers>' list are
  384. used for shift level calculation and then discarded. Sometimes this is not
  385. desirable. If you want to use a modifier for shift level calculation but you
  386. don't want to discard it, you may list in 'preserve[<combination of modi-
  387. fiers>]=<list of modifiers>'. That means, for a given combination all listed
  388. modifiers will be preserved. If the Lock modifier is preserved then the
  389. resulting symbol is passed to internal capitalization routine regardless
  390. whether it has been used for a shift level calculation or not.
  391.  
  392. Any key type description can use both real and virtual modifiers. Since real
  393. modifiers always have standard names it is not necessary to explicitly
  394. declare them. Virtual modifiers can have arbitrary names and can be declared
  395. (prior using them) directly in key type definition:
  396.  
  397.      virtual_modifiers <comma-separated list of modifiers>  ;
  398.  
  399. as seen in for example basic, pc or mousekeys key type definitions.
  400.  
  401. 4.3  Rules
  402.  
  403. Once you are finished with your symbol map you need to add it to rules file.
  404. The rules file describes how all the five basic keycodes, types, compat, sym-
  405. bols and geometry components should be composed to give a sensible resulting
  406. xkb configuration.
  407.  
  408. The main advantage of rules over formerly used keymaps is a possibility to
  409. simply parameterize (once) fixed patterns of configurations and thus to ele-
  410. gantly allow substitutions of various local configurations into predefined
  411. templates.
  412.  
  413. A pattern in a rules file (often located in /usr/lib/X11/xkb/rules) can be
  414. parameterized with four other arguments: Model, Layout, Variant and Options.
  415. For most cases parameters model and layout should be sufficient for choosing
  416. a functional keyboard mapping.
  417.  
  418. The rules file itself is composed of pattern lines and lines with rules. The
  419. pattern line starts with an exclamation mark ('!') and describes how will the
  420. xkb interpret the following lines (rules). A sample rules file looks like
  421. this:
  422.  
  423.      ! model                   =   keycodes
  424.        macintosh_old                     =   macintosh
  425.        ...
  426.        *                       =   xorg
  427.  
  428.      ! model                        =   symbols
  429.        hp                      =   +inet(%m)
  430.        microsoftpro                 =   +inet(%m)
  431.        geniuscomfy                  =   +inet(%m)
  432.  
  433.      ! model       layout[1]          = symbols
  434.        macintosh    us           = macintosh/us%(v[1])
  435.        *             *               =       pc/pc(%m)+pc/%l[1]%(v[1])
  436.  
  437.      ! model     layout[2]            = symbols
  438.        macintosh     us              =  +macintosh/us[2]%(v[2]):2
  439.        *       *               =   +pc/%l[2]%(v[2]):2
  440.  
  441.      ! option            =    types
  442.        caps:internal               =    +caps(internal)
  443.        caps:internal_nocancel =    +caps(internal_nocancel)
  444.  
  445. Each rule defines what certain combination of values on the left side of
  446. equal sign ('=') results in. For example a (keyboard) model macintosh_old
  447. instructs xkb to take definitions of keycodes from file keycodes/macintosh
  448. while the rest of models (represented by a wild card '*') instructs it to
  449. take them from file keycodes/xorg. The wild card represents all possible val-
  450. ues on the left side which were not found in any of the previous rules.  The
  451. more specialized (more complete) rules have higher precedence than general
  452. ones, i.e. the more general rules supply reasonable default values.
  453.  
  454. As you can see some lines contain substitution parameters - the parameters
  455. preceded by the percent sign ('%'). The first alphabetical character after
  456. the percent sign expands to the value which has been found on the left side.
  457. For example +%l%(v) expands into +cz(bksl) if the respective values on the
  458. left side were cz layout in its bksl variant. More, if the layout resp. vari-
  459. ant  parameter is followed by a pair of brackets ('[', ']') it means that xkb
  460. should place the layout resp. variant into specified xkb group. If the brack-
  461. ets are omitted the first group is the default value.
  462.  
  463. So the second block of rules enhances symbol definitions for some particular
  464. keyboard models with extra keys (for internet, multimedia, ...) . Other mod-
  465. els are left intact. Similarly, the last block overrides some key type defi-
  466. nitions, so the common global behaviour ''shift cancels caps'' or ''shift
  467. doesn't cancel caps'' can be selected. The rest of rules produces special
  468. symbols for each variant us layout of macintosh keyboard and standard pc sym-
  469. bols in appropriate variants as a default.
  470.  
  471. 4.4  Descriptive Files of Rules
  472.  
  473. Now you just need to add a detailed description to <rules>.xml description
  474. file so the other users (and external programs which often parse this file)
  475. know what is your work about.
  476.  
  477. 4.4.1  Old Descriptive Files
  478.  
  479. The formerly used descriptive files were named <rules>.lst Its structure is
  480. very simple and quite self descriptive but such simplicity had also some cav-
  481. ities, for example there was no way how to describe local variants of layouts
  482. and there were problems with the localization of descriptions. To preserve
  483. compatibility with some older programs, new XML descriptive files can be con-
  484. verted to old format '.lst'.
  485.  
  486. For each parameter of rules file should be described its meaning. For the
  487. rules file described above the .lst file could look like:
  488.  
  489.      ! model
  490.        pc104        Generic 104-key PC
  491.        microsoft    Microsoft Natural
  492.        pc98         PC-98xx Series
  493.        macintosh     Original Macintosh
  494.        ...
  495.  
  496.      ! layout
  497.        us      U.S. English
  498.        cz      Czech
  499.        de      German
  500.        ...
  501.  
  502.      ! option
  503.        caps:internal           uses internal capitalization. Shift cancels Caps
  504.        caps:internal_nocancel uses internal capitalization. Shift doesn't cancel Caps
  505.  
  506. And that should be it. Enjoy creating your own xkb mapping.
  507.  
  508.  
  509. $XdotOrg: xc/programs/xkbcomp/README.enhancing,v 1.3 2004/09/03 23:41:22 kem Exp $
  510.